home *** CD-ROM | disk | FTP | other *** search
/ AGA Toolkit '97 / The AGA Toolkit '97.iso / miscellaneous / help / dos / dosman / man / list < prev    next >
Encoding:
Text File  |  1996-09-07  |  13.5 KB  |  341 lines
  1.  
  2.  
  3.  
  4.                   List(V1.3, 2.x, 3.x in C:)
  5.  
  6.  
  7.  
  8.      NAME
  9.           List - List contents of a directory.
  10.  
  11.      SYNOPSIS
  12.           List listname Dir P=PAT/k KEYS/s DATES/s NODATES/s SUB/k
  13.                SINCE/k SORT/s TO/k UPTO/k QUICK/s BLOCK=BLOCKS/s
  14.                NOHEAD/s FILES/s DIRS/s LFORMAT/k
  15.  
  16.      DESCRIPTION
  17.             List displays the contents of a given directory.  By 
  18.         contents, we mean the names of the subordinate files and 
  19.         directories, not the file data.  Typing the List command 
  20.         by itself with no parameters generates a listing of the 
  21.         current directory. It also lists any comments attached by 
  22.         a FILENOTE command.
  23.  
  24.      THE LISTING DISPLAY
  25.             List displays your files and directories one per 
  26.         line, with all the protection flags currently turned on 
  27.         right next to the filename.  The fields which may appear 
  28.         in a Listed file are
  29.  
  30.           name [KEY] size/type protection date time
  31.           :comment
  32.  
  33.             Methods are provided for getting a selective listing 
  34.         of files, as well as suppressing/adding most of the above 
  35.         display elements.  
  36.  
  37.             A description of each one of the above elements is 
  38.         given below:
  39.  
  40.           Name 
  41.             The name of the file or directory. This can be a 
  42.         device or volume name. AmigaDOS wildcards are supported 
  43.         100%.  The inclusion of wildcards eliminates the need for 
  44.         the P (or PAT) keyword. PAT is retained to keep 
  45.         compatiblility with older versions of AmigaDOS.
  46.  
  47.           KEY
  48.             This is the actual block number of the file or 
  49.         directory block header.  This is not displayed by 
  50.         default, you must use the KEYS switch to generate this 
  51.         element of the listing.
  52.  
  53.           size/type
  54.             This element gives the size of the file in bytes, or 
  55.         the string "empty" if the file is empty. If this is a 
  56.         directory and not a file, then the directory indicator 
  57.         ("Dir") will appear here.
  58.  
  59.           protection
  60.             The protection bits of the current file, in the order 
  61.         hsparwed.  If any of these is disabled, a dash (-) will 
  62.         appear in its place. The protection bits stand for 
  63.         "hidden, script, pure, archived, read, write, execute and 
  64.         delete", respectively.
  65.  
  66.           date time
  67.             The date and time of the last modification to the 
  68.         file or directory.  The format of the date display is 
  69.         determined by the value of the environment variable 
  70.         dateformat.  These elements of the listing appear by 
  71.         default, but may be selectively added or subtracted by 
  72.         using the DATES or NODATES keywords.
  73.  
  74.           comment
  75.             The comment as set by Filenote.  If no comment 
  76.         exists, this field will not be displayed.  Note that it 
  77.         is displayed on a line by itself, preceded by a colon.
  78.  
  79.  
  80.      SELECTIVE LISTING OF FILES
  81.             The methods described in this section allow you to 
  82.         list a portion of the files and directories on your 
  83.         disks. Ways exist to generate a list of files that 
  84.         conform to a certain pattern, or that were 
  85.         created/modified before or after a certain date.  You may 
  86.         also combine these options, for example, you may get a 
  87.         list of all files which end in .c and were created or 
  88.         modified since a certain date. These options are 
  89.         described below:
  90.  
  91.           Dir  
  92.             List this directory instead of the current directory.  
  93.         This parameter may be a filename, in which case the 
  94.         single file is shown.  You may also use any legal 
  95.         AmigaDos pattern in this position, in which case the 
  96.         files and directories listed will be those which match 
  97.         the pattern, if any.  (This feature was added to the BCPL 
  98.         List in the V1.3 enhancer.)
  99.  
  100.           PAT 
  101.             List only files and directories which match the 
  102.         pattern. You must specify the keyword PAT or its 
  103.         abbreviation P.  This is no longer truly necessary with 
  104.         the expanded capabilities of AmigaDOS wildcards, since it 
  105.         is usually more convenient to simply include the pattern 
  106.         in the directory specification as described above.  It is 
  107.         included for BCPL compatibility.
  108.  
  109.           SUB  
  110.             In this option the SUB keyword must come before the 
  111.         string. If spaces are in the string, it must be enclosed 
  112.         in quotes. With the inclusion of AmigaDOS wildcards, this 
  113.         keyword is really not needed. It searches for an 
  114.         occurence of the substring anywhere within the directory 
  115.         name or filename.  Think of this as a short form of "List 
  116.         PAT *substring*" or a long form of "List *substring*".  
  117.         List will reject any attempts to combine the use of PAT 
  118.         and S.  Wildcards in the initial DIR argument are matched 
  119.         and then checked again to match against the substring.
  120.  
  121.           SINCE
  122.             While the pattern matching options above filter files 
  123.         and directories on the basis of their names, this option, 
  124.         and the following UPTO option, filter out files based on 
  125.         their last modification date. SINCE displays only files 
  126.         which have been created or modified on or later than the 
  127.         specified date.  All older files are not displayed.  You 
  128.         may specify the date in the currently defined dateformat 
  129.         (see Environment Variables) or you may use a word such as 
  130.         SUNDAY, TODAY, YESTERDAY, etc.
  131.  
  132.           UPTO 
  133.             The inverse of SINCE, this option displays only files 
  134.         and directories which have been modified or created on or 
  135.         before the specified date.  Files younger than this date 
  136.         are not displayed. See SINCE for a description of the 
  137.         date format list expects.
  138.  
  139.           FILES
  140.             Display only files, and not the directories.
  141.  
  142.           DIRS
  143.             Display only directories, and not the files.
  144.  
  145.      CONTROLLING THE DISPLAY
  146.             The options below allow you to alter the format of 
  147.         the display listing, or to send it to another file or 
  148.         output display device (that's usually a printer).
  149.  
  150.           TO   
  151.             You can specify a file or a device you wish the 
  152.         listing to be sent to using this keyword.  If not 
  153.         specified, the default of the current screen will be 
  154.         used. If the file already exists then the old file will 
  155.         be replaced (and gone forever) while being replaced with 
  156.         this new file. If the protection bit is set on the old 
  157.         file LIST will not work. It is very useful to LIST TO 
  158.         prt: to get a hard copy of your disk listing.
  159.  
  160.           DATES
  161.             Forces the date and time of creation to be displayed 
  162.         in the current dateformat. This keyword does not have to 
  163.         be used unless you are using the QUICK or NODATES 
  164.         keywords. 
  165.  
  166.           NODATES
  167.             Will not display time and date information, only the 
  168.         filename, size, protection and comment fields will be 
  169.         displayed. Using DATES with this will force the creation 
  170.         dates and times to display.
  171.  
  172.           QUICK
  173.             Displays only the filename field, one filename per 
  174.         line, with no trailing spaces. You can LIST just the 
  175.         files or direcotries by using the FILES or DIR options.  
  176.         You can combine this with other options such as DATES and 
  177.         KEYS to selectively enable these fields.  Under 2.x/3.x 
  178.         KEYS no longer works with this keyword.
  179.  
  180.           KEYS 
  181.             Displays the block number of each file header or 
  182.         directory header. All files are assigned using block 
  183.         numbers. This is how AmigaDOS keeps track of your files.  
  184.         Each file has a unique block number assigned to it.  This 
  185.         is its address on the disk. The block number appears to 
  186.         the left of the file length.
  187.  
  188.           SORT 
  189.             Sorts the file and directory names into ascending 
  190.         alphabetical order.  Case is disregarded. Note that this 
  191.         is an option available only with the ARP list.  Sorts by 
  192.         DATE if you include the DATES keyword.
  193.  
  194.           BLOCK=BLOCKS
  195.             Displays filesizes in blocks, rather than bytes.
  196.  
  197.           NOHEAD
  198.             Suppresses the default "Directory..." header and the 
  199.         "x files -x directories -x blocks used" footer display.
  200.  
  201.           LFORMAT
  202.             LFORMAT can be used to control the output of list, 
  203.         and especially to generate command lines to be fed to the 
  204.         shell. LFORMAT can is most useful when you want to 
  205.         generate a script file. To send the LIST output to a 
  206.         script file, you can either redirect LIST's output using 
  207.         the ">" or "TO" keywords. LFORMAT takes a string as an 
  208.         argument which can be any ascii string.  
  209.  
  210.             The LFORMAT substring can be used multiple times. 
  211.         This allows you to use the listing name more than once 
  212.         per line. The second time you use the string the first 
  213.         relative path will be replaced by %S, and the path of the 
  214.         second argument will be used (BTW, a relative path is 
  215.         merely the list of directories you must traverse to get 
  216.         from the specified directory to the current one.) If you 
  217.         use three substrings, then the first will be replaced by 
  218.         the relative path, while the second and third will be the 
  219.         file or subdirectory names. If you use it four times, the 
  220.         first and third will be the relative paths, and the 
  221.         second and fourth will be the subdirectory or file names.
  222.  
  223.             To include the output of List in this string, you can 
  224.         use the "%S" sequence under 1.3 or 2.x/3.x as follows:
  225.  
  226.                   "%S"       Filename
  227.                   "%S%S"     Pathname/Filename
  228.                   "%S%S%S"   Pathname/FilenamePathname
  229.                   "%S%S%S%S" Pathname/FilenamePathname/Filename
  230.  
  231.             The following information may be substituted for the 
  232.         string as output and is for 2.x/3.x Only:
  233.  
  234.                 %A   :Attributes (protection flags)
  235.                 %B     :Size of file in blocks
  236.                 %C     :Comments attached to the file
  237.                 %D     :Date of file creation or last update
  238.                 %F     :The complete absolute path (starting with the 
  239.                       volume name)
  240.                 %K     :Key block number
  241.                 %L     :Length of the file in bytes
  242.                 %N     :Name of the file
  243.                 %P     :The relative path(starting at the current directory)
  244.                 %T     :Time of creation or last update
  245.  
  246.             The following information may be substituted for the 
  247.         string as output and is for 2.1/3.x Only:
  248.  
  249.                 %E     :Extension only (the part of the filename after the
  250.                       last period)
  251.                 %M     :Filename minus the extension (everything up to
  252.                       the last period)
  253.                 ALL  :Lists the contents of all the subdirectories of the
  254.                       specified directory, as well as the directory itself.
  255.  
  256.             The %S's may be separated by spaces, other ascii text 
  257.         or nothing, as above.  Here is an example of LFORMAT that 
  258.         will create a script to Type each file:
  259.  
  260.                List LFORMAT="Type %S%S"
  261.  
  262.             Of course, to use this, you must save it in a file 
  263.         using TO or one of the IO Redirection operators ('>', 
  264.         '>>').  If you are using 2.x/3.x, you can also pipe the 
  265.         output of List directly into the Execute command.  
  266.  
  267.      ENVIRONMENT VARIABLES
  268.             The List uses the same dateformat variable as used by 
  269.         the Date command, and in essentially the same way.  If it 
  270.         is not defined, or if it has an illegal value, the 
  271.         default AmigaDOS display and input is used.  Otherwise, 
  272.         the display and the input of dates is determined as 
  273.         follows:
  274.  
  275.           0    AmigaDOS format DD-MMM-YY.
  276.  
  277.           1    International format YY-MM-DD.
  278.  
  279.           2    U.S. format MM-DD-YY.
  280.  
  281.           3    Canada DD-MM-YY
  282.  
  283.             If you prefix the above numbers with a dash, then the 
  284.         display of names like TODAY, MONDAY, FUTURE, etc., will 
  285.         be disabled and the format string as defined above will 
  286.         be used exclusively. Note that this governs the format 
  287.         that List expects as input as well as the format List 
  288.         uses for display.
  289.  
  290.      EXAMPLES
  291.           
  292.             1. To display all files in df1: ending with the 
  293.         characters "#?.c" which were modified later than TUESDAY 
  294.         at 00:00 hours.
  295.  
  296.             List df1:#?.c SINCE WEDNESDAY
  297.  
  298.             2. To output just the names and dates for items in 
  299.         the current directory beginning with the letters 'stuff' 
  300.         that were created or last updated on or before April 16, 
  301.         1967. Sent the output out to a file called 'StuffOut' in 
  302.         the Ram:T directory.
  303.  
  304.             LIST stuff#? QUICK DATES UPTO 16-Nov-67 TO Ram:T/StuffOut
  305.  
  306.  
  307.             3. To list the information about the contents of the 
  308.         current CLI directory.
  309.  
  310.             LIST
  311.  
  312.  
  313.             4. To print the block number of all the files in the 
  314.         current directory.
  315.  
  316.             LIST KEYS to PRT:
  317.  
  318.                 or
  319.  
  320.             LIST > PRT: KEYS
  321.  
  322.  
  323.             5. To display the information about the files in the 
  324.         directory art/adult whose names contain the string 
  325.         'girls'
  326.  
  327.             LIST art/adult/#?girls#?
  328.  
  329.             (note: Information about both 'Really Ugly Girls' and 
  330.               PrettyGirls would be displayed)
  331.  
  332.  
  333.             6. To set the pure bit of every file in the stuff: 
  334.         directory.
  335.  
  336.             LIST >RAM:ThisFile stuff:#? LFORMAT "protect %S +p"
  337.     
  338.             (now you have a file called Ram:ThisFile which contains
  339.             the commands to set the PROTECT bit on all the files in the
  340.             stuff: directory. Now, just EXECUTE RAM:ThisFile
  341.